Release 10.1A: OpenEdge Development:
Progress Dynamics Administration

Upgrade files

The XML files that specify the changes the DCU applies to the Repository and application databases are the upgrade files. Each upgrade file is assigned to a patch level that controls when the DCU applies the upgrade. The data in an upgrade file should generally be limited to one of the following categories:

New database creation data.
A list of all ADOs to load during a given patch level.
Upgrade programs, including:
Schema changes
Data loads
Fix programs

After patch level “0,” the next patch level is the lowest one that can be applied during the upgrade. A patch level can have multiple files associated with it. Upgrade files are listed in a specific order under the database node. All the upgrade files for a given patch file are listed together. The DCU parses the files in the order they are listed under the database node.

Database creation upgrade files

The first patch level listed under the database nodes controls the creation of new databases. The new database creation patch level is always numbered “0.” The associated upgrade file provides the details for building a new database, as in the standard Repository build file shown:

icfdbbuild.xml

<?xml version="1.0" encoding="utf-8" ?> <SetupInclude>   <Patch PatchLevel="0">     <patchstage UpdateStage="Delta">       <Program>         <FileType>df</FileType>         <FileName>db/icf/dfd/icfdbfull.df</FileName>         <Description>Applying Full DB Schema</Description>         <Rerunnable>no</Rerunnable>         <NewDB>yes</NewDB>         <ExistingDB>no</ExistingDB>         <UpdateMandatory>yes</UpdateMandatory>       </Program>     </patchstage>     <patchstage UpdateStage="DataLoad">       <Program>         <FileType>d</FileType>         <FileName />         <Description>Loading database table contents</Description>         <Rerunnable>no</Rerunnable>         <NewDB>yes</NewDB>         <ExistingDB>no</ExistingDB>         <UpdateMandatory>yes</UpdateMandatory>       </Program>       <Program>         <FileType>s</FileType>         <FileName />         <Description>Setting site number</Description>         <Rerunnable>yes</Rerunnable>         <NewDB>yes</NewDB>         <ExistingDB>no</ExistingDB>         <UpdateMandatory>yes</UpdateMandatory>       </Program>     </patchstage>   </Patch> </SetupInclude>

There are several points to observe in this file. An upgrade file can contain information on several programs that run at different stages. The patch stages must be listed in the correct order. The programs within a patch stage must be listed in the order in which you want them to run.

A peculiarity of this file is that it does not list specific filenames for the programs in the DataLoad stage. The DCU automatically loads all the files of the appropriate type in the target directory.

Note: For an explanation of the program attribute nodes, see the "Upgrade program attributes" section.

After patch level “0,” the other patch levels are listed in ascending order from the lowest one that can be applied during the upgrade. A patch level can have multiple files associated with it. The files are listed in the order the DCU should apply them.

ADO list upgrade files

The ADO list upgrade file is usually the largest upgrade file. This file contains a list of all the ADOs that are applied during a patch level. The ADO list upgrade file is created by the release versioning tools. The tools automatically list the ADOs in the order in which they should be applied. For more information on the release versioning tools, see the Progress Dynamics Version 2.1A Application Deployment white paper at the following PSDN Web site:

http://psdn.progress.com/library/white_papers/dynamicswp/index.ssp

Note: The release versioning tools build a completely new ADO list file each time. Any edits you made in a previous ADO list are lost, so generally you should not customize the file.

The following excerpt is from an ADO list file:

icfdb100002adolist.xml

<?xml version="1.0" encoding="utf-8" ?> <SetupInclude>   <Patch PatchLevel="100002">     <PatchStage Stage="ADOLoad">       <Program>         <FileType>ADO</FileType>         <FileName>db/icf/dump/gscem.ado</FileName>         <Description>Loading ADO for db/icf/dump/gscem.ado</Description>         <Rerunnable>yes</Rerunnable>         <NewDB>no</NewDB>         <ExistingDB>yes</ExistingDB>         <UpdateMandatory>yes</UpdateMandatory>       </Program>       <Program>         <FileType>ADO</FileType>         <FileName>db/icf/dump/gscer.ado</FileName>         <Description>Loading ADO for db/icf/dump/gscer.ado</Description>         <Rerunnable>yes</Rerunnable>         <NewDB>no</NewDB>         <ExistingDB>yes</ExistingDB>         <UpdateMandatory>yes</UpdateMandatory>       </Program>

Other upgrade files

The other upgrade files that might be part of a patch level detail the steps to upgrade an existing database, including schema updates, data loads through ADOs, and programs to fix existing data. A file can include several procedures happening at various stages of the upgrade process.

The following example shows the XML structure for applying a schema change and running a procedure file:

icfdb020026patch.xml

<?xml version="1.0" encoding="utf-8" ?> <SetupInclude>   <Patch PatchLevel="020025">     <PatchStage Stage="Delta">       <Program>         <FileType>df</FileType>         <FileName>db/icf/dfd/icfdb020025delta.df</FileName>         <Description>Applying 020025 Delta</Description>         <Rerunnable>no</Rerunnable>         <NewDB>no</NewDB>         <ExistingDB>yes</ExistingDB>         <UpdateMandatory>yes</UpdateMandatory>       </Program>     </PatchStage>     <PatchStage Stage="PreADOLoad">       <Program>         <FileType>p</FileType>         <FileName>db/icf/dfd/fixrmdhtmlattr.p</FileName>         <Description>Removing old DHTML attribute deletions</Description>         <Rerunnable>yes</Rerunnable>         <NewDB>no</NewDB>         <ExistingDB>yes</ExistingDB>         <UpdateMandatory>no</UpdateMandatory>       </Program>     </PatchStage>   </Patch> </SetupInclude>